﻿<!DOCTYPE HTML>
<html lang="en">
<head>
<title>Error 对象 | AutoHotkey v2</title>
<meta name="description" content="Error objects thrown by built-in code when an error occurs." />
<meta name="ahk:equiv-v1" content="AutoHotkey.htm" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>Error 对象</h1>
<pre class="NoIndent">class Error extends Object</pre>

<p>Error(错误) 对象是由内置代码在运行时发生错误时<a href="../commands/Throw.htm">抛出的</a>, 也可由脚本显式抛出. 以下是标准属性:</p>

<p id="Message"><strong>Message:</strong> 错误消息.</p>
<p id="What"><strong>What:</strong> 引起异常的原因. 这通常是一个函数的名称, 但对于由表达式中的错误而抛出的异常(例如在非数字值上使用数学运算符), 则为空白.</p>
<p id="Extra"><strong>Extra:</strong> 与错误有关的字符串值(如果有). 如果这个值可以转换为非空字符串, 标准错误对话框会显示一行 "Specifically:" 后面跟着这个字符串.</p>
<p id="File"><strong>File:</strong> 包含发生错误的行或构造错误对象的脚本文件的完整路径.</p>
<p id="Line"><strong>Line:</strong> 错误发生的行号, 或者错误对象被构造的行号.</p>
<p id="Stack"><strong>Stack:</strong> 代表 Error 对象被构造时的调用栈的字符串. 每一行的格式如下:</p>
<dl>
  <dt><code><i>File</i> (<i>Line</i>) : [<i>What</i>] <i>SourceCode</i>`r`n</code></dt>
  <dd>代表对函数 <em>What</em> 的调用. <em>File</em> 和 <em>Line</em> 表示该堆栈深度下的当前脚本行. <em>SourceCode</em> 是该行源代码的近似值, 就像 <a href="../commands/ListLines.htm">ListLines</a> 中显示的那样.</dd>
  <dt><code>&gt; <i>What</i>`r`n</code></dt>
  <dd>表示线程的启动, 通常是它上面的函数调用的直接原因.</dd>
  <dt><code>... <i>N</i> more</code></dt>
  <dd>表示堆栈跟踪被截断, 还有 <em>N</em> 个堆栈条目没有显示. 目前 <code>Stack</code> 属性不能超过 2047 个字符.</dd>
</dl>

<p class="warning"><strong>注意:</strong> 标准错误对话框要求 <em>Message</em>, <em>Extra</em>, <em>File</em> 和 <em>Line</em> 都是<a href="Object.htm">自有值属性</a>.</p>

<h2 id="new">Error()</h2>
<p>创建 Error 对象.</p>
<pre class="Syntax">NewError := <span class="func"><i>Error</i></span>(Message <span class="optional">, What, Extra</span>)</pre>
<p><em><strong>Error</strong></em> 可以用 <a href="#error-types">Error 类型</a>中列出的某个子类替换, 尽管一些子类可能会采用不同的参数.</p>
<p>这些参数直接对应于上面描述的属性, 但对于覆盖 __New 方法的 Error 子类来说, 参数可能有所不同.</p>
<p><em>Message</em> 和 <em>Extra</em> 被转换为字符串. 如果一个异常抛出而且没有被捕获, 则会通过一个错误对话框来显示它们.</p>
<p><em>What</em> 指示错误的来源. 它可以是任意字符串, 但应该是负整数或正在运行的函数的名称. 指定 -1 表示当前函数, -2 表示调用它的函数, 依此类推. 如果脚本被<a href="../Scripts.htm#ahk2exe">编译</a>或者该值不能识别有效的堆栈帧, 那么该值将被转换为字符串并赋值给 <code>NewError.What</code>. 否则, 将使用标识的堆栈帧来确定其他属性:</p>
<ul>
  <li><code>NewError.What</code> 包含函数的名称.</li>
  <li><code>NewError.Line</code> 和 <code>NewError.File</code> 表示 <em>调用</em> 函数的行.</li>
  <li><code>NewError.Stack</code> 包含部分堆栈跟踪, 在顶部指示堆栈帧.</li>
</ul>
<p>使用 <em>What</em> 参数可以允许复杂函数使用帮助函数来执行其工作或参数验证, 同时从任何报告的错误信息中忽略这些内部细节. 例如:</p>
<pre>MyFunction(a, b) {
    CheckArg "a", a
    CheckArg "b", b
    <em>;...</em>
    CheckArg(name, value) {
        if value &lt; 0
            throw ValueError(name " is negative", "myfunction", value)
    }
}

try
    MyFunction(1, -1)  <em>; err.Line 显示为这一行.</em>
catch ValueError as err
    MsgBox Format("{1}: {2}.`n`nFile:`t{3}`nLine:`t{4}`nWhat:`t{5}`nStack:`n{6}"
        , type(err), err.Message, err.File, err.Line, err.What, err.Stack)</pre>
<pre>try
    SomeFunction()
catch as e
    MsgBox(type(e) " in " e.What ", which was called at line " e.Line)

SomeFunction() {
    throw Error("Fail", -1)
}</pre>

<h2 id="error-types">Error 类型</h2>

<p><strong>Error</strong> 的以下子类是预定义的:</p>
<ul>
  <li id="IndexError"><strong>IndexError(索引错误)</strong>: 试图使用对象的 <a href="../Objects.htm#__Item">__Item 属性</a>在无效索引处赋值或检索项, 该属性通常通过<a href="../Variables.htm#square-brackets">项访问操作符</a>(也称为索引操作符) 访问.<ul>
    <li id="KeyError"><strong>KeyError</strong>: Map 使用的 IndexError 的子类.</li>
  </ul></li>
  <li id="MemberError"><strong>MemberError(成员错误)</strong>: 试图访问未定义的属性或方法. <strong>Message</strong> 指示要调用的值的类型和属性或方法的名称. 此错误类型不直接使用; 而是使用下面的一个子类.<ul>
    <li id="PropertyError"><strong>PropertyError(属性错误)</strong></li>
    <li id="MethodError"><strong>MethodError(方法错误)</strong></li>
  </ul></li>
  <li id="MemoryError"><strong>MemoryError(内存错误)</strong>: 内存分配失败.</li>
  <li id="OSError"><strong>OSError(系统错误)</strong>: 对 Win32 函数的内部函数调用失败. <strong>Message</strong> 包括操作系统生成的错误码和描述. OSErrors 有一个额外的 <strong>Number</strong> 属性, 其中包含错误代码. Calling <code>OSError(code)</code> with a numeric <em>code</em> sets <em>Number</em> and <em>Message</em> based on the given OS-defined error code. 如果 <em>code</em> 被省略, 则默认为 <code>A_LastError</code>.</li>
  <li id="TargetError"><strong>TargetError(目标错误)</strong>: 函数由于找不到目标而失败. <strong>Message</strong> 指示目标的类型, 例如窗口, 控件, 菜单或状态栏.</li>
  <li id="TimeoutError"><strong>TimeoutError(超时错误)</strong>: <a href="../commands/SendMessage.htm">SendMessage</a> 超时.</li>
  <li id="TypeError"><strong>TypeError(类型错误)</strong>: 意外的值类型被用作函数, 属性赋值或其他操作的输入. 通常 <strong>Message</strong> 指示预期的和实际的类型, 而 <strong>Extra</strong> 包含一个表示错误值的字符串.</li>
  <li id="ValueError"><strong>ValueError(值错误)</strong>: 意外的值被用作函数, 属性赋值或其他操作的输入. 通常 <strong>Message</strong> 指示哪个期望值被打破, 而 <strong>Extra</strong> 包含一个表示错误值的字符串.</li>
  <li id="ZeroDivisionError"><strong>ZeroDivisionError(零除错误)</strong>: 在表达式或 Mod 函数中试图除以零.</li>
</ul>
<p>也可以使用基 Error 类来抛出 Error.</p>

<h2 id="Related">相关</h2>
<p><a href="../commands/Throw.htm">Throw</a>, <a href="../commands/Try.htm">Try</a>, <a href="../commands/Catch.htm">Catch</a>, <a href="../commands/Finally.htm">Finally</a>, <a href="../commands/OnError.htm">OnError</a></p>

</body>
</html>